home *** CD-ROM | disk | FTP | other *** search
/ Magnum One / Magnum One (Mid-American Digital) (Disc Manufacturing).iso / d19 / kmail275.arc / KMAIL.DOC < prev    next >
Text File  |  1991-04-26  |  24KB  |  546 lines
  1.                        Kmail Version  2.74
  2.                          Copyright 1990
  3.                                by
  4.                            Ken Krueger
  5.  
  6.                          Twin  Peaks  BBS
  7.  
  8.              (303)-651-0225 - Hayes Ultra v.32 v.42bis
  9.  
  10. Specifications:
  11. ---------------
  12.  
  13.   Produces QWK compatible mail packets.
  14.   Reads CNAMES.@@@ to obtain conference information.
  15.   Reads TPA to obtain User information.
  16.   Updates USER file via USERS.SYS interface.
  17.   Resets "Mail Waiting" flags after a successful packet download.
  18.   Sets message 'has-been-read" flag after successful download.
  19.   Sets message-has-replies flag when appropriate.
  20.   Fully network compitable. Opens all files in share mode.
  21.   Locks message base during updating.
  22.   Supports 1024 conferences.
  23.   Message packets compatible with RNET.
  24.   Extended conference packets require RNET v1.07 or later.
  25.   Message packets tested with EZ-RDR v1.33 and SLMR v1.05.
  26.   Produces pre-scanned mail packets to save online time.
  27.  
  28.  
  29. Evaluation
  30. ----------
  31.  
  32.   This evaluation  version of  Kmail is  provided so  that you  and your
  33. users may may decide  if this program meets  your needs.  Kmail  is 100%
  34. fully functional for the "sysop" in local mode.  The callers are limited
  35. to 10 messages per conference and to 50 total messages per packet.
  36.  
  37. In addition, you may call Twin Peaks and obtain a one time 60-day full
  38. function demo-key to help complete your evaluation. No fuss no muss,
  39. first time callers can obtain the demo-key.
  40.  
  41.  
  42. 60 Day Demo Key
  43. ---------------
  44.  
  45.   To obtain the 60 day demo key, just call Twin Peaks. Join conf #19
  46. open door 9 and follow the instructions.
  47.  
  48.   In order for the Demo-Key to work, the name you use to register on
  49. Twin Peaks MUST exactly match the name in record #1 of your USERS file.
  50.  
  51.  
  52. Requirements
  53. ------------
  54.  
  55.    Dos 3.1 or greater.
  56.    PCBoard 14.5 or 14.5a
  57.    DSZ     version 05/25/89 or later.
  58.    PKZIP   v1.10 or higher.
  59.    PK361   If you wish to support the ARC format.  (optional)
  60.    PUMA    If you wish to make it available.       (optional)
  61.  
  62. Installation
  63. ------------
  64.  
  65.    1. Create a KMAIL sub-directory to hold the Kmail distribution files.
  66.       Place all files in the archive into this directory.
  67.  
  68.    2. Create a work sub-directory such as C:\KWORK for Kmail to use.
  69.       ***CAUTION***  ***CAUTION***     All files are erased in this
  70.       directory during the mail packet creation process. DO NOT use an
  71.       existing directory that has good stuff in it!  Multi-node systems
  72.       must have a unique work area for each node.
  73.  
  74.    3. Customize the KMAIL.CFG file. Ample comments are in the sample.
  75.       This is where you really customize the overall operation.
  76.       Parms 1-4 are passed along to the mail readers for their use.
  77.       While not critical, you should keep to the general outline in
  78.       the sample and customize them for your system.
  79.  
  80.  ==>  PARM 5: This one is important! This parm specifies the name of
  81.       the QWK mail packet that Kmail will create. While the name can be
  82.       anything, it would be best to have a name that is associated
  83.       with your BBS system name. (Do not specify a .extension here).
  84.  
  85.       The rest of the parms are optional. Among them are options to
  86.       control the number of messages based on connect speed, and
  87.       protocol transfer options. The default values are in the sample.
  88.  
  89.       DSZ is used as the main protocol and is activated via a call
  90.       to a BAT file which you may define in the KMAIL.CFG file. This
  91.       allows you to totally customize the DSZ parms to suit your
  92.       system. I just let it default to the standard PCBxx.BAT files
  93.       that I have setup for PCBoard. Be sure to include the BAT files
  94.       location in your DOS path! Kmail passes parms %1-%5 to the
  95.       BAT files just the same as PCBoard.
  96.  
  97.  
  98.       When a caller requests ╔════════════════════════════════════════╗
  99.       an external protocol,  ║       External Protocol Parameters     ║
  100.       PCBoard passes several ╠═════════╦══════════════════════════════╣
  101.       parameters to the      ║Parameter║         Description          ║
  102.       protocol batch file.   ╠═════════╬══════════════════════════════╣
  103.       These parameters are   ║   %1    ║COM Port Number.              ║
  104.       listed to the right.   ╟─────────╫──────────────────────────────╢
  105.                              ║   %2    ║PC to Modem Speed (DTE rate)  ║
  106.                              ╟─────────╫──────────────────────────────╢
  107.                              ║   %3    ║Filename to transfer.         ║
  108.                              ╟─────────╫──────────────────────────────╢
  109.                           ** ║   %4    ║Connect Speed shown by PCBoard║
  110.                              ╟─────────╫──────────────────────────────╢
  111.                              ║   %5    ║Carrier Speed.                ║
  112.                              ╚═════════╩══════════════════════════════╝
  113.  
  114.      ** The %4 field is not easily determined within Kmail, therefore
  115.         upon exit to the protocol BAT files, Kmail adjusts the %4
  116.         field to the same value as %5.
  117.  
  118.  
  119.       I have found the following works well with my Hayes 9600 v.42.
  120.  
  121.         PCBSZ.BAT
  122.               dsz ha bo est 0 %5 pB4096 sz -m %3
  123.  
  124.         PCBRZ.BAT
  125.               dsz ha slow est 0 %5 pB4096 z pr1 rz -m -p %3
  126.  
  127.  
  128.    4. Customize the KMAIL.CNF if necessary. This is a 2 or 3 line file.
  129.       The 1st line defines the interface routine that Kmail should
  130.       use, and the 2nd line defines the location of a work directory.
  131.  
  132.       If you are running a multi-node system, you will need a unique
  133.       CNF file for each node. (KMAIL1.CNF, KMAIL2.CNF, KMAIL3.CNF......)
  134.  
  135.  
  136.       Line #1 can be ONE of the two following examples:
  137.  
  138.         INTERRUPT   ;the best, fastest
  139.         BIOS        ;if interrupt fails to work or if
  140.                     ;running under a multi-tasker
  141.  
  142.       Line #2 is the path\name of a scratch work directory. If the
  143.       sub-directory does not exist, it will be created. The name may
  144.       be anything. I use the name KWORK on my system.
  145.  
  146.       Line #3 is optional. If the pre-zip function (explained later) is
  147.       used, this line points to the holding sub-directory. It may be
  148.       any name, but I recommend something like KHOLD. Multi-node
  149.       systems MUST share the same KHOLD sub-directory in order for
  150.       pre-zip packets to be located from any node.
  151.  
  152.  
  153.         Sample KMAIL.CNF
  154.  
  155.         INTERRUPT       Line 1
  156.         C:\KWORK        Line 2  <-- Must be unique for each node!
  157.         D:\KHOLD        Line 3  Optional, must NOT be the same as
  158.                                 line 2. Multi-node systems must
  159.                                 share the same sub-directory.
  160.  
  161.   ********************************************************************
  162.   **  Warning   **  Warning  **  Warning  **  Warning  **  Warning  **
  163.   ********************************************************************
  164.   *                                                                  *
  165.   *   ALL FILES ARE ERASED IN THE WORK DIRECTORY DURING PROCESSING.  *
  166.   *   MAKE SURE THE AREA YOU SPECIFY IS A SCRATCH AREA!              *
  167.   *                                                                  *
  168.   *     C:\KWORK    <=== NOTE: All files erased in this dir.         *
  169.   *                                                                  *
  170.   ********************************************************************
  171.   **  Warning   **  Warning  **  Warning  **  Warning  **  Warning  **
  172.   ********************************************************************
  173.  
  174.  
  175.    5. Create the BAT file to run the Kmail door. Kmail requires two
  176.       parameters when it is called. The 1st parameter specifies the
  177.       name of the CONFIG file. The 2nd parameter specifies the
  178.       the drive and path to your PCBoard main directory where the
  179.       PCBOARD.DAT file is located.
  180.  
  181.       Echo off
  182.       SET KMAIL=
  183.       CD\Kmail
  184.       KMAIL KMAIL.CNF C:\PCB
  185.       C:
  186.       CD\PCB
  187.       If exist event.bat event             <<<--- take note
  188.       Board
  189.  
  190.    Notice line 6.  This line will start your timed event if needed.  Any
  191.    door that can logoff a user (during carrier loss or with goodbye) has
  192.    the possibility of starting the event.
  193.  
  194.  
  195.    6. Add an entry in your DOORS.LST files for Kmail. Indicate that
  196.       a USERS.SYS *SHOULD* be created and that a DOOR.SYS should not
  197.       be created when Kmail is executed.
  198.  
  199.    7. Using PCBsm, select "User Info File Maintenance" and create
  200.       a KMAIL Third Party Application entry with the following info.
  201.  
  202.       Version      :    25
  203.       Static Size  :     4
  204.       Dynamic Size :     1
  205.       Keyword      : KMAIL    <---- Watch this one! See note below.
  206.  
  207.       NOTE: The keyword parameter above must match the name of the BAT
  208.             file that is used to open the Kmail door. So, if the name
  209.             of your BAT file is something else, change the keyword
  210.             parameter accordingly.
  211.  
  212.    8. Kmail will use the DOS Environment variable "COMSPEC=" to locate
  213.       COMMAND.COM in order to execute the archive and communications
  214.       programs. The location of the archive and communication programs
  215.       must also be included in your DOS path.
  216.  
  217.    9. Network Qnet Status:
  218.  
  219.       If your system will be acting as a HUB for other systems, then
  220.       you will need to create a QNET.DAT file to control the Qnet status
  221.       of the downline systems. The QNET.DAT file is a plain ordinary
  222.       text file which contains the names of the downline sysops whom
  223.       you wish to grant Qnet status. One name per line starting in
  224.       column 1 and EXACTLY 1 space between the first and last name.
  225.       Mixed case is ok. The QNET.DAT file should be placed in the
  226.       Kmail sub-directory. Qnet status permits a user to upload mail
  227.       on behalf of another person. Without Qnet status, a user is limited
  228.       to uploading only their own personal mail.
  229.  
  230.       (* ----------------------------------------------------------- *)
  231.       (* The sequence of names should NEVER be changed and new names *)
  232.       (* must only be added to the end of the file. If you need to   *)
  233.       (* remove a person from the list, then just XXX their name out *)
  234.       (* leaving the XXX's as a placeholder.                         *)
  235.       (* ----------------------------------------------------------- *)
  236.  
  237.       NOTE: I apologize for the shoddyness of this procedure. I am
  238.             working on a PCBsm type utility to handle this function.
  239.             It is high on the priority list and expect to have something
  240.             around the middle of 1991.
  241.  
  242.       The letter 'Q' is displayed on the conference selection screen
  243.       beside each conference to indicate Qnet status.
  244.  
  245.       If you have one or more conferences that you do not want echoed
  246.       to downline systems, setting the conference echo-flag to NO will
  247.       disable Qnet status for that conference. Messages can still be
  248.       downloaded for offline reading via a RDR, but cannot be merged
  249.       into the system message base.
  250.  
  251.   10. PRE-ZIP'ed mail packets.
  252.  
  253.       This function allows you to scan and zip a mail packet for a
  254.       user so that it is ready for download when the user calls in.
  255.       This is an especially usefull function for LD callers.
  256.  
  257.       You will need to create a sub-directory to serve as a holding
  258.       area for the pre-zipped packets. The location of the holding
  259.       directory is specified in the Kmail.cnf file as shown in step
  260.       (5) above. Multi-node systems may share the same holding area.
  261.  
  262.       A PREZIP.DAT file must be created in the Kmail sub-directory
  263.       which lists each sysop's name and assigns a unique sequence
  264.       number to each name. The sequence numbers are used to match up
  265.       a pre-zip packet with the proper caller and are not associated
  266.       with any other function in Kmail. Pre-zip packets will be
  267.       stored in the KHOLD directory until downloaded by the caller.
  268.       The users "MSG Pointers" are also stored in the KHOLD directory
  269.       and are posted to the users record upon successful downloading
  270.       of the pre-zip packet.
  271.  
  272. Note: The following format must be *STRICTLY* adheared to. The
  273.       name begins in column #1 and must not exceed 25 characters.
  274.       A comma MUST sepatate the name and it's following sequence
  275.       number. All names must have a three digit sequence number
  276.       following the name, leading zeros REQUIRED!  Mixed case is
  277.       allowed in the name. No two users should have the same number!
  278.  
  279.    Sample: PREZIP.DAT
  280.  
  281.       George Washington,026
  282.       John Smith,015
  283.       Bob Jones,009
  284.  
  285.  
  286.       I would suggest a SET Kmail= in your door bat file to insure
  287.       that PREZIP is never active for an online caller.
  288.  
  289.       Prezip processing is activated via a Kmail=PREZIP DOS environment
  290.       variable. The following is suggested in your event.sys file.
  291.  
  292.       Basically, the process is to make a call to PCB145 to build a
  293.       USERS.SYS followed by a call to Kmail to create the packet.
  294.  
  295.       Important! The use of : and ; at the appropriate places in the
  296.                  PCB145 command line is critical!!!
  297.  
  298.          Ex:  PCB145 /USERSYS;JOHN;SMITH;PWRD:12345;TPA:KMAIL
  299.                                                         ^^^^^
  300.       Carefull, this parm must match the bat file name.   |
  301.       ____________________________________________________|
  302.  
  303.       EVENT.SYS
  304.       ...
  305.       ...
  306.       Set Kmail=PREZIP              <===== (note CAPS)
  307.       cd\pcb
  308.       PCB145 /USERSYS;JOHN;SMITH;PWRD:12345;TPA:KMAIL
  309.       cd\Kmail
  310.       Kmail KMAIL.CNF C:\PCB LOCAL
  311.       cd\pcb
  312.       PCB145 /USERSYS;JOE;DOAKS;PWRD:FOOBAR;TPA:KMAIL
  313.       cd\Kmail
  314.       Kmail KMAIL.CNF C:\PCB LOCAL
  315.       If Exist USERS.SYS Del USERS.SYS
  316.       Set Kmail=                 <===== Important!! I suggest you also
  317.       ...                               include this line in your Kmail
  318.       ...                               door BAT file(s).
  319.       event continues.....
  320.  
  321.  
  322.   11. The installation of Kmail is now complete and you are ready to
  323.       begin initial testing as soon as everything is backed up!!!
  324.  
  325.  
  326.   12. Insure that the locations of DSZ and PKZxxx programs are defined
  327.       in your DOS path. Kmail will be unable to locate them if they
  328.       are not in the Dos path!
  329.  
  330.  
  331.     **** NOTE WELL **** NOTE WELL **** NOTE WELL **** NOTE WELL ****
  332.     **** NOTE WELL **** NOTE WELL **** NOTE WELL **** NOTE WELL ****
  333.     **** NOTE WELL **** NOTE WELL **** NOTE WELL **** NOTE WELL ****
  334.  
  335.   Obviously a  mail door  must update  the USERS  file to  store message
  336. pointers.  Please make sure your USERS file is backed up before  running
  337. Kmail.  There has  been one report of  trashed message pointers.   I was
  338. unable to track down the cause of the problem and it has not re-occured.
  339.  
  340.   Do not fall  into the trap  of making an  automatic backup each  night
  341. during  your  event  if  you  are  simply overlaying the previous nights
  342. backup.  If  a problem did  occur and you  did not catch  it for several
  343. days, you wouldn't have a valid backup copy.  I suggest that you keep  a
  344. minimum of seven grandfather copies of  your USERS file and each one  of
  345. them should be unique.
  346.  
  347.  
  348. Conferences
  349. -----------
  350.  
  351.   Kmail obtains all conference  related information from the  CNAMES.@@@
  352. file including  such items  as MSG  base location,  required security to
  353. join, and bulletins path/location.
  354.  
  355.   If  a  user  does  not  have  the  required  security  level to join a
  356. conference,  the  conference  will  be  listed  as <closed> on the Kmail
  357. conference selection menu.
  358.  
  359.   If you need to  delete a conference for  any reason, just insure  that
  360. the conference  name is  blanked out  using PCBsetup  and Kmail will not
  361. attempt to  process it.   It  will show  up as  *Empty* on the selection
  362. menu. Remember to do a global delete of the registered and scan flags!
  363.  
  364.  
  365. Private (R/O) Messages
  366. ----------------------
  367.  
  368.   Kmail will validate the caller  security level and compare it  against
  369. the appropriate values specified in  PCBsetup to determine if access  to
  370. to private messages including comments to sysop are allowed.  Conference
  371. Sysop status  is also  checked.   As with  PCBoard, you  may give global
  372. access to private messages by assigning a high enough security, or on  a
  373. conference by conference basis by assigning conference-sysop status.
  374.  
  375.  
  376. Qnet_Private=No/Yes    (Default=No)
  377. -------------------
  378.  
  379.   If you wish to allow  Network-Sysop's the ability to download  private
  380. mail without having to alter security levels, you can do this be putting
  381. the parameter Qnet_Private=Yes in the Kmail.CFG file.  However, R/O msgs
  382. that do not have  the "Echo" flag set,  will not be sent.   In addition,
  383. the same rule  applies to the  conference "Echo-flag" status.   In other
  384. words, for a R/O message to qualify using the Qnet_Private= option, both
  385. the conference Echo flag  AND the individual msg  Echo flag must be  set
  386. on.  Comments to Sysop are not included with this option.
  387.  
  388.  
  389. Ignore_Echo=No/Yes     (Default=No)
  390. ------------------
  391.  
  392.   This option only has meaning if you will be operating as a network hub
  393. with downline nodes receiving mail from  you.  When you enable a  caller
  394. for network-status, that status  only applies to conferences  defined as
  395. "echo" conferences  in pcbsetup.   Besides  "main", you  may have one or
  396. more local conferences on  your system.  If  you wish to allow  downline
  397. nodes  to  echo  your  local  conferences  including main, then set this
  398. option to Yes.
  399.  
  400.  
  401. Zip_Opt=xxx
  402. -----------
  403.  
  404.   If for some reason you  need/want Kmail to use unique  Zip parameters,
  405. you may specify them using this option.  Omit this entry unless you have
  406. a specific reason for using it.
  407.  
  408.  
  409. Loc_Dir=path            (Default=None)
  410. ------------
  411.  
  412.   If you plan to use Kmail in local mode to capture mail to use with  an
  413. offline RDR,  use this  parameter to  specify the  location where  Kmail
  414. should place the  QWK packet.   Kmail will also  retrieve the REP  files
  415. from this directory.  This parm is only  for convenience.  An  alternate
  416. location may be specified during the execution of Kmail.
  417.  
  418.  
  419. Scan_Upld_Only=Yes/No   (Default=Yes)
  420. ---------------------
  421.  
  422.   This  option  controls  whether  just  the  upload  directory  or  ALL
  423. directories are scanned when the caller  selects the new file scan.   If
  424. you keep new files in the upload directories for several days/weeks then
  425. setting this option to  YES would be the  best choice.  However,  if you
  426. move new files out of the upload area rather quickly or perhaps have the
  427. "make all uploads private" switch enabled in PCB, then you will need  to
  428. specify NO for this option to prevent callers from missing new files.
  429.  
  430.   The scanning of new  files is limited to  the conference in which  the
  431. door was opened.  Private upload directories are NEVER scanned.
  432.  
  433.  
  434. SCRIPT0 File
  435. ------------
  436.  
  437.   If a SCRIPT0 file is present  in the KMAIL directory, it will  be sent
  438. along in the mail packet.  The SCRIPT0 file is displayed by the  various
  439. readers  when  the  user  exits  the  reader.    If you use one of those
  440. programs that generate  a different SCRIPT0  every day, you  may want to
  441. consider copying  it over  to the  Kmail directory  during system  event
  442. processing.
  443.  
  444.  
  445. Getting Started
  446. ---------------
  447.  
  448.   Finally it's time to run Kmail.   Just login to the BBS in the  normal
  449. way and open  Kmail door.   As a first  time user, you  will be asked to
  450. answer some  configuration questions  as will  each user  when they  try
  451. Kmail the first time.  A  special feature in Kmail will detect  when the
  452. "sysop" is in local mode and  will issue a prompt asking where  to place
  453. the resulting QWK mail  packet.  You should  respond with the drive  and
  454. path, but WITHOUT the  trailing back-slash after the  name.  Use of  the
  455. Loc_Dir option described above prevents having to type this each time.
  456.  
  457.        c:\temp     \      All of these are valid ways to specify the
  458.        d:\ez        >--   location of where to place the QWK  packet
  459.        a:          /      when running in local mode.
  460.  
  461.   Later on when you are ready to upload any replies created with one  of
  462. the offline readers, Kmail will ask  where to obtain the REP file.   Use
  463. the same format as above to specify the location.
  464.  
  465.  
  466. Errors
  467. ------
  468.  
  469.   Any errors detected by kmail  including those from 3rd party  programs
  470. such as PKZip  and DSZ are  logged into a  file called $door.err  in the
  471. Kmail sub-directory.  In addition,  many of the errors are  also written
  472. to the  caller log  file.   Error information  is also  displayed to the
  473. callers.
  474.  
  475.  
  476. Notes and Misc Info
  477. -------------------
  478.  
  479.   Kmail  sends  a  KMAIL.PTR  file  in  each  mail packet.  The PTR file
  480. contains the last-read message pointer for each conference that the user
  481. has selected.  In the event of a problem, a user may upload the PTR file
  482. to restore the message pointers.   Just extract the KMAIL.PTR  file from
  483. the QWK packet and zip it up in a BBSID.REP file and upload it to  Kmail
  484. using the 'P' menu option.
  485.  
  486.  
  487.   The user may select/un-select  conferences and reset message  pointers
  488. by using the  appropriate options in  EZ-RDR.  Review  the documentation
  489. associated  with  EZ-RDR  for  additional  information.   When resetting
  490. message pointers, Kmail will accept an absolute message # or a  negative
  491. number such  as -25  which means  set the  message pointer  equal to  25
  492. messages from the end of the message base.
  493.  
  494.   Not yet documented on the menu screen is the ability to stack commands
  495. for the  download process.   The  command 'D  Y' will  download the mail
  496. packet and return you to the menu screen, while 'D G' will download  and
  497. log you off.  A 10 second timer is provided to allow you to change  your
  498. mind.  By using  stacked commands, the user  can avoid the question  "Do
  499. you wish to receive this packet?"
  500.  
  501.   Recent changes to PCBoard allow for passing command line parms to door
  502. programs. Kmail now takes advantage of this feature. Assuming  Kmail was
  503. installed as door #3, the following commands would be valid.
  504.          Open 3 d       (open the door & start download scan)
  505.          Open 3 d y     (open the door, scan mail, yes to download)
  506.          Open 3 d g     (open the door, scan mail, download & goodbye)
  507.         Kmail d y       (open the door, scan mail, yes to download)
  508.  
  509.  
  510. In The Works
  511. ------------
  512.  
  513. Utility to handle Qnet status and view/change user options.
  514.  
  515. Online and downloadable help information is planned.
  516.  
  517. A filter to allow a user to not receive messages from selected users.
  518.  
  519. Acknowledgements
  520. ----------------
  521.  
  522. Special thanks to Bill Walsh, whose system I crashed many times during
  523. early beta testing, and to Jeff Freeman whose eagle eye caught many
  524. potential problems, and to Ken Flower for testing >256 conferences.
  525. And thanks to the many others who played a part in the beta testing
  526. development of Kmail.
  527.  
  528.  
  529. Registration
  530. ------------
  531.  
  532.   Please see the file KMAIL.REG for registration information.
  533.  
  534.   After receipt of your registration, you  will need to call my BBS  and
  535. obtain a customized KEY file, which will enable any and all features not
  536. available  in  the  evaluation  copy  of  Kmail.    Currently,  the only
  537. limitation is the number of messages allowed per mail packet.
  538.  
  539.   After obtaining your customized KMAIL.KEY file, just place it in  your
  540. KMAIL sub-directory to activate all features.
  541.  
  542.  
  543.                                  Ken Krueger
  544.                                  Twin Peak's BBS
  545.                            303-651-0225 - Hayes Ultra 9600 v.32
  546.